home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgramD2.iso / Borland / Borland C++ V5.02 / DOC.PAK / ADDON.TXT next >
Text File  |  1997-05-06  |  18KB  |  468 lines
  1. ADDON.TXT For BCWADDON.DLL v1.02  doc rev 1.7 7/4/96
  2. Note: v1.02 of bcwaddon.dll corresponds with v5.01 of BCW
  3.  
  4. BCW 5.0 AddOn Interfaces
  5. ------------------------
  6.  
  7. The BCW AddOn Interfaces provide a mechanism to help achieve tight integration
  8. between a third party addon application and the BCW C++ IDE. The interfaces
  9. are implemented using the OLE COM model and a basic understanding of COM
  10. is essential to developing an addon using these interfaces. This document
  11. doesn't attempt to explain COM or cover all the interfaces in great detail.
  12. It does provide an an overview of the types of services available and how to
  13. get started. In many cases, detailed reference material is provided in the
  14. header files. In some cases, it may be necessary to take a close look at the
  15. provided examples, since the documentation may not be complete yet.
  16.  
  17. Several of the interfaces have been brought forward from BC4.5's IDEHOOK
  18. implementation. They have minor changes that allow them to conform to
  19. a new set of rules and to behave more like the new interfaces. In most
  20. cases, if you have code that used IDEHOOK, that code can be brought forward
  21. without any major restructuring.
  22.  
  23. As we add features and services to the addon wrapper dll, we will surface new
  24. interfaces to access those services, while leaving the old interfaces intact.
  25.  
  26. AddOn Requirements:
  27. - Addons must be written as Win32 DLL's and will be loaded by the IDE's process
  28.   (BCW.EXE) when properly registered with the system as being a BCW addon.
  29. - Addons must be written in a language that supports COM interfaces
  30.  
  31. Notes:
  32. - At the time of this writing, only C++ headers are provided.
  33. - It is not required that the addon dll be written using OWL or be built
  34.   using Borland tools.
  35. - As an addon developer, you should be familiar with the concept and rules of
  36.   reference counting as it is used in OLE programing. You should also have at
  37.   least some familiarity with COM interfaces.
  38.  
  39. Services exposed through the AddOn interfaces
  40. - Commands and Menus
  41. - View mgmt
  42. - Editor buffers
  43. - Virtual file system
  44. - Make engine
  45. - Addon pages for option dialogs (MPD's)
  46. - Project mgmt
  47. - Status bar
  48. - Script engine
  49. - Target options
  50. - Tool mgmt
  51. - Custom Targets
  52. - Message window output
  53.  
  54. Known bugs and bug fixes
  55. ------------------------
  56. 1) (not yet fixed) You must compile and link into your dll a provided file
  57. ADDON.RC if you are creating MPD pages. This file can be found in the
  58. include\ideaddon directory.
  59.  
  60. 2) (FIXED in v1.01) The top level project node sometimes returns info for its
  61. first child instead of itself.
  62.  
  63. 3) (FIXED in v1.02 - see IPOLYSTR.H comment below) Only the "Cstr" methods of
  64. IPolyString are currently hooked up.
  65.  
  66. 4) (FIXED in v1.01) When using the NewFileMessage() or NewMessage() methods of
  67. IMessageFolder, passing strings to the pMsg argument larger than 230 bytes in
  68. length will crash BCWADDON.DLL. We will fix this in a patch, but for now you
  69. must truncate the strings before creating the poly string object that gets
  70. passed to the method.
  71.  
  72. 5) (FIXED in v1.01) Destructors on interface objects weren't being called when
  73. the object's ref count reached zero.
  74.  
  75. 6) (FIXED in v1.01) There was to prevent restoration of an addon view on a
  76. subsequent project open (see new comment above IViewClient::GetRestoreDataLen()
  77. in iview.h).
  78.  
  79. 7) (FIXED in v1.01) Allow the creation of new tabs (as documented) when
  80. creating a new message window folder (imsgsys.h).
  81.  
  82. 8) (FIXED in v1.01) Using IVirtualFile, Exists() required a previous call to
  83. Open() and Close() was not automatically called when the ref count reached
  84. zero - they now behave as documented in ivfile.h.
  85.  
  86. 9) (FIXED in v1.02) Several IEditorServer methods weren't working correctly:
  87. backspace(), raise_anchor(), delete_to_eol(), page_down(), page_up(). This
  88. has been fixed.
  89.  
  90. 10) (FIXED in v1.02) Addon MPD pages with conflicting resource IDs would
  91. sometimes cause a page to fail to repaint.
  92.  
  93. 11) (FIXED in v1.02) New BC5 lib types were not represented in ITARG.H.
  94.  
  95. 12) (FIXED in v1.02) The doc in IEDITOR.H was misleading, since it was always
  96. necessary to call set_buffer() after any call to begin_edit() and this was not
  97. stated in the doc. This is still the desired calling sequence, but protection
  98. has been built into begin_edit() to make the call to set_buffer() non-essential
  99. in cases where the correct buffer is already current.
  100.  
  101. 13) (FIXED in v1.02) The return from AddRef() on interface objects in
  102. BCWADDON.DLL and those created with IUnknownImpl was the refcount before the
  103. AddRef() instead of after.
  104.  
  105. 14) (FIXED in v1.02) The speedbar editor in Options/Environment would display
  106. bitmaps for commands that had no bitmap associated with them. Now, commands
  107. with no associated bitmap will not show up in the speedbar editor at all. In
  108. other words, commands for which ICommand::SetIcons() is never called will not
  109. appear in the speedbar.
  110.  
  111. 15) (FIXED in v1.02) An add-on's view managed window, in cases where it was the
  112. only opened view in the IDE, would sometimes hang or crash when the user would
  113. try to access the file or edit menus.
  114.  
  115. 16) (FIXED in v1.02) The GUID variable names in itx.uid were misspelled and
  116. didn't adhere to the convention used in the comhelp.h macros. The fix to this
  117. is to continue to support the old names through macro definitions while
  118. correcting the mistake.
  119.  
  120. 17) (FIXED in v1.02) Fixed crash bug involving ev_notify messages for Win95
  121. Common Controls that happen to be placed in mpd pages.
  122.  
  123. 18) (FIXED in v1.02) ITargetServer::TargetAdd() and ConvertNodeToTarget() were
  124. not working correctly for 16 bit DOS targets, this has been fixed.
  125.  
  126. 19) (FIXED in v1.02) IProjectClient::CloseNotify() was being called
  127. prematurely, giving the user the opportunity to cancel the close after this
  128. method had been called. The timing has been adjusted so that the CloseNotify()
  129. happens later in the cycle when there is no possibility of the close being
  130. aborted.
  131.  
  132.  
  133. New In 5.01
  134. -------------------
  135. COMHELP.H
  136. Added QUERY_INTERFACE() macro, see EXAMPLES\IDE\ADDON\TESTBED\PRJVIEW.CPP for
  137. an example usage.
  138.  
  139. IVIEW.H
  140. Added IViewType2 interface for extended view display name and family name
  141. support (see comments in IVIEW.H along with the definition of IViewType2).
  142.  
  143. IPOLYSTR.H
  144. Hooked up BSTR support. Decided to cop out on Delphi string support, since
  145. this would be of limited added convenience or performance improvement over
  146. just doing the conversion to or from 'c' strings in your Delphi code.
  147.  
  148. ITOOL.H
  149. Two new flags have been added to support having your tool appear on the File|New
  150. submenu or having your tool appear in the viewer list in the File|Open
  151. dialog. They are TIFlag_OnFileNewMenu and TIFlag_OnFileOpenMenu.
  152.  
  153. IPROJ.H
  154. IProjectServer2 exposes node flags, see iproj.h for more details
  155.  
  156. IMSGSSYS.H
  157. Added IMessageSystem2 and IMessageClient for hooking an action request on a
  158. message - suitable for use by a third party source editor that wants to handle
  159. user double-clicks on error messages. See imsgsys.h for more info, also see
  160. the example in bc5\examples\ide\addon\testbed\msgcli.h and .cpp.
  161.  
  162. Add IMessageFolder2, which adds support for including a help file and context
  163. id when creating a message. See the imsgsys.h for more info, and the example
  164. in bc5\examples\ide\addon\testbed\msgtest2.h and .cpp.
  165.  
  166. IPRSET.H
  167. Added IPrinterSettings interface for determining the current printer settings
  168. when they have been changed from the default via the Printer Setup dialog box.
  169. See iprset.h for details. See bc5\examples\ide\addon\testbed\prset.cpp and .h
  170. for example code.
  171.  
  172. IPROJ.H
  173. Added IProjectSaveClient. This is directly related to bugfix #19 above.
  174. Now that CloseNotify() is being called at the right time, it is no longer
  175. effective to remove add-on tools in response to CloseNotify(). It is harmless
  176. to do so, but it is too late for the changed toolset to be saved with the
  177. project. To remedy the situation, IProjectSaveClient has been added, which
  178. calls the add-on right before a project is saved and again right after it has
  179. been saved. See IPROJ.H for more details.
  180.  
  181.  
  182. New in 5.02
  183. -----------
  184.  
  185. IIDEUI.H
  186. Added IIdeUI interface to allow addon's access to the IDE's set of message boxes.
  187.  
  188. ISTATUS.H
  189. Added IStatusDialog interface to give addon's access to the IDE's status dialog.
  190.  
  191. ITOOL.H
  192. Added IToolInfo3 interface to allow addon's to retrieve the IStatusDialog interface.
  193.  
  194. IPROJ.H
  195. Added IProjectServer3 interface. This interface gives addon's the ability to move
  196. and copy individual nodes; set the translator on a specific node; retieve the
  197. autodependency information of a specific node; and set the dirty flag for a node.
  198. See IPROJ.H for details.
  199.  
  200. IEDITOR.H
  201. Added IEditorServer2 to give addon's ability to have IDE reload an edit buffer from
  202. disk.
  203.  
  204.  
  205. C++ IDE AddOn Interfaces
  206. ------------------------
  207. File Locations
  208. Addon wrapper dll: bc5\bin\bcwaddon.dll
  209. Examples: bc5\examples\ide\addon\testbed
  210. Interfaces: bc5\include\ideaddon
  211. Registry tool: bc5\bin\addonreg.exe
  212.  
  213. Getting Started
  214. ---------------
  215. - Registering your dll at install time -
  216. Add your addon dll key in the registry under the following key:
  217.  
  218. HKEY_LOCAL_MACHINE
  219.  SOFTWARE
  220.   Borland
  221.     Borland C++
  222.      5.0
  223.       IDE
  224.         AddOns
  225.          (addon client keys...)
  226.  
  227. Key: "testbed example" (the name of your addon)
  228.   Value: "Path"   Data: "c:\bc5\bin\exaddon.dll" (full path to your dll)
  229.   Value: "Enabled"  Data: "Yes"
  230.  
  231. During development, you can use addonreg.exe to quickly add, delete, enable
  232. and disable addon registry entries (or to see exactly what the entry should
  233. look like).
  234.  
  235. exaddon.dll (used in the above example) is our example testbed, which weÆll
  236. talk about in a minute.
  237.  
  238. Your dll MUST have one special entry point, which bcwaddon.dll will call to
  239. let you know that the IDE is waking up and shutting down:
  240.  
  241. extern "C" void WINAPI __export BcwAddOnEntry( IIdeServer * pIdeServer ) {
  242.   if ( pIdeServer ) { // the ide is waking up
  243.    SetIdeServer( pIdeServer )
  244.    // do initialization stuff here...
  245.   }
  246.   else { // the ide is shutting down
  247.    // do cleanup stuff here...
  248.    ReleaseIdeServer();
  249.   }
  250. }
  251.  
  252. The code for SetIdeServer(), ReleaseIdeServer() and other handy things is
  253. provided in comhelp.h/cpp, which can be found in the include\ideaddon
  254. directory.
  255.  
  256. Once your dll is registered, the addon wrapper, BCWADDON.DLL, will dynamically
  257. load your dll at startup time and call BcwAddOnEntry(). There is no way to
  258. specify that your dll will be loaded in any particular order with respect to
  259. other addon dll's. Once your dll is loaded, you can schedule scripts to run
  260. and register to receive events via one or more client interfaces. Server
  261. interfaces are provided to call into the IDE and to register client
  262. interfaces. All server interfaces are available by querying the IIdeServer
  263. pointer passed in to BcwAddOnEntry() or through the macro GET_INTERFACE().
  264.  
  265. - Testbed -
  266. Since weÆre trying to be efficient, we thought weÆd combine the concept of
  267. example code with smoke testing and bug reproduction. We set up a small test
  268. framework for which we are providing source code (see the examples directory).
  269. As we add tests, they will appear in the source that is delivered to you.
  270.  
  271. The testbed is built in the examples\ide\addon\testbed directory.
  272.  
  273. To build and install the testbed:
  274. - Open the exaddon.ide project and build it
  275. - Copy exaddon.dll to your bc5 bin directory
  276. - Copy the *.spp files to your bc5 script directory
  277. - From the bin directory, launch ADDONREG.EXE and create a new entry
  278.   for exaddon.dll (pointing to the copy in the bin directory).
  279. - Shut down the ide and start it up again.
  280.  
  281. If properly installed, you should see a dialog box appear just before BCW does.
  282. From this dialog box, you can select a test object and run up to 4 sub-tests
  283. once the object has been initialized (with the initialize button). To run
  284. another set of tests, uninitialize the current object and select another one. An
  285. output window is right there in the dialog box which shows debug messages
  286. generated from exaddon.dll.
  287.  
  288. It is very easy to add your own tests to this framework. The test
  289. harness is heavily commented in some places. See examples\tests.h/cpp and
  290. option.h/cpp to get started. A more advanced example is in project.h/cpp.
  291. One test which covers a lot of ground is the view management test.
  292. YouÆll also notice some macros from include\ideaddon\comhelp.h used in these
  293. examples to make the COM implementation simpler.
  294.  
  295. - Interfaces -
  296. The interfaces are all in the include\ideaddon directory. YouÆll notice that
  297. weÆre using IPolyString whenever strings need to be passed across the
  298. interface. There are helper functions in use to make this easier to deal with.
  299. We need to stay away from using C++ constructs or structs across the interface
  300. and want to be able to accommodate BSTR usage (and Pascal strings) with a
  301. minimum of conversion overhead, hence, the IPolyString interface. Be sure to
  302. read the doc in ipolystr.h before using them. (Note: only the 'c' string
  303. methods have been implemented at the time of this writing, the others are
  304. no-ops).
  305.  
  306. - Script Interface -
  307. There are many ways to talk with the IDE through the IDEÆs Object Script
  308. implementation and the script interface provides a way to run individual script
  309. commands and entire scripts through the AddOn interface. When the IDE is first
  310. coming up, you can schedule your startup script through the
  311. ScheduleScriptFile() method. You can issue short commands through
  312. RunScriptCommand() and load and unload script files with RunScriptFile() and
  313. UnloadScriptFile(). This is quite powerful, since you can expose flat function
  314. calls in your dlls that can be called directly from script and a lot of the
  315. internal APIÆs are already exposed as script objects. (Please take note
  316. of the warning in iscript.h regarding calling script from within anything
  317. but the UI thread).
  318.  
  319.  
  320. Interface Overview
  321. ------------------
  322. IPolyString
  323. Utility used for string conversion-on-demand, ref counting/ownership
  324. Supports: c-style strings (pascal strings and BSTR support coming soon)
  325. File: IPolyStr.h
  326.  
  327. IIde
  328. Exposes: Application-wide methods, access to all server interfaces through
  329. QueryInterface, and creation of miscellaneous object instances.
  330. File: IIde.h
  331.  
  332. IScriptServer
  333. Exposes: Access to the script engine
  334. File: IScript.h
  335. Notes:
  336.   Run or schedule script files, issue script commands.
  337.  
  338. IProjectServer, IProjectClient, IProjectNodeInfo
  339. Exposes:
  340.   Project node attributes
  341.   Node Iteration, Find by name
  342.   Custom node properties
  343.   Events: Open, Close, NodeAdd/Delete and others
  344.   Node Add/Remove
  345.   Selected nodes
  346. File: IProj.h
  347.  
  348. ICommand, ICommandServer
  349. Exposes: Command creation, management
  350. File: ICmd.h
  351. Notes:
  352.   Enabler callback
  353.   Command implemented in script, can call back to your dll
  354.   Can register icon for speedbar
  355.  
  356. IMenuItem, IMenuClient, IMenuServer
  357. Exposes: Frame, Project and Editor menus
  358. File: IMenu.h
  359. Notes:
  360.   Hook up menu items to ICommand objects
  361.   Event when a menu is about to open
  362.  
  363. IViewClient, IViewParentWnd, IUserViewFactory, IViewType
  364. Exposes: Addon view management
  365. File: IView.h
  366. Notes:
  367.   Addon windows become descendants of an ide mdi client
  368.   Restore opportunity, your restore data saved with ide project
  369.   Polymorphic command support
  370.   View type can be added to the Font and Color property page list
  371.   View is managed (tile, cascade, etc.)
  372.  
  373. IMpdPage, IMpdChapter, IMpdServer
  374. Exposes: Project and environment option dialogs
  375. File: IMpd.h
  376. Notes:
  377.   Addon chapters and pages for MultiPageDialog's
  378.   (Chapter contains one or more pages)
  379.   Project MPD's are node-specific
  380.   OnCommand() event for mgmt, or can subclass
  381.  
  382. IStatusBar
  383. Exposes: Ability to write text to status bar, status bar hwnd
  384. File: ISBar.h
  385.  
  386. IToolImplementor, IToolInfo, IToolServer
  387. Exposes: Tool mgr
  388. File: ITool.h
  389. Notes:
  390.   Invoke any registered tool
  391.   Find tool by name
  392.   Register Addon callbacks as tools
  393.   Register standalone tools
  394.  
  395. IVirtualFile
  396. Exposes: Virtual file system
  397. File: IVFile.h
  398. Notes:
  399.   Low-level file routines
  400.   Edit buffers are used for READING of files already loaded into an edit buffer
  401.   Disk files are used otherwise
  402.  
  403. IEditorServer
  404. Exposes: Editor
  405. File: IEditor.h
  406. Notes:
  407.   Create and delete edit buffers
  408.   Manipulate text in buffer
  409.   Line editing
  410.   Iterate open buffers
  411.   Create system (hidden) buffers
  412.   Save a buffer to disk
  413.   Regular expression searching and translation
  414.   Behavior can't be overridden in script
  415.   Undo/Redo access
  416.  
  417. IMakeClient, IMakeServer
  418. Exposes: Access to the make engine
  419. File: IMake.h
  420. Notes:
  421.   Make Begin and End events
  422.   Node input/output age
  423.   Make node(s)
  424.  
  425. IOptionServer
  426. Exposes: Build options for a node
  427. File: IOption.h
  428. Notes:
  429.   Set/Get the following build options:
  430.    Include path spec
  431.    Library path spec
  432.    Source path spec
  433.    Intermediate output path
  434.    Final output path
  435.    #defines
  436.    Command line override
  437.  
  438. ITargetServer
  439. Exposes: Target add, query
  440. File: ITarg.h
  441. Notes:
  442.    Add a specified target
  443.    Get target attributes
  444.    Find a node's target
  445.  
  446. IMessageSystem, IMessageFolder
  447. File: iMsgSys.h
  448. Notes:
  449.   Allows you to Post messages to a folder in the message window
  450.  
  451.  
  452. ITargetManager
  453. File: iTx.h
  454. Notes:
  455.   Use this and the other interfaces in itx.h to create a custom target type
  456.   that will appear in the TargetExpert
  457.  
  458.  
  459. Important Note
  460. --------------
  461. In order to provide you with the most comprehensive product information,
  462. updates, and service possible with this new release of Borland C++ and its
  463. associated products we are providing several online resources.
  464.  
  465. For the location of these resources and information  on contacting Borland and
  466. support services offered by Borland, please read the file 'README.TXT' in your
  467. \BC5 directory.
  468.